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Abstract 


Over the years, many documents from IMAPEXT and LEMONADE working 
groups, as well as many individual documents, have added syntactic 
extensions to many base IMAP commands described in RFC 3501. For 
ease of reference, this document collects most of such ABNF changes 
in one place. 


This document also suggests a set of standard patterns for adding 
options and extensions to several existing IMAP commands defined in 
RFC 3501. The patterns provide for compatibility between existing 
and future extensions. 


This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. 
It also includes part of the errata to RFC 3501. This document 
doesn’t specify any semantic changes to the listed RFCs. 


Melnikov & Daboo Standards Track [Page 1] 


RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 


Table of Contents 


a 


Lis 


OU ® W 


ti 


TRAE COAUCGE LOM seal ie ane niča s Seah ee oe eta See tee eee da BES, 2 
Lels PurposeOf This: Document: gda kaba BAGA SIRE ZVE bide 2 
1.2. Conventions Used in This Document «e ole Ne ai E eS 3 
IMAP SABNE MXP STIS ONS: ns i le ei do SU A egy SARA Sh Stier a enn’ 3 
2.1. Optional Parameters with the SELECT/EXAMINE Commands ....... 3 
223 Extended CREATE Command: 44024 6 lene bih Na a a HbA SA Sid BEA eee 4 
2.3:, Extended: RENAME: Command ee dne goa ese eS ae i a ele, 5 
2.4. Extensions to FETCH and UID FETCH Commands ................. 6 
2.5. Extensions to STORE and UID STORE Commands ................. 6 
Z 6, Extenslons'to SEARCH Command. ie state sists hoot eeu Soe ee eee hist ele oe die 7 
Ž6 TU, “Extended. SEARCH Command: se sesa slaw ae NA dnje nd Sl dje diš 7 
2.6.2. ESEARCH untagged response ....... cece ee ee ea a nn ne a 8 
2:1: Extensions: ‘to APPEND ‘Command: e aaa NE A Ed aed BSE ees 8 
Formal. SVntaš + ave Sie: og tel ek ep le lads SoS ie Spel cee Se “ERLE podate aj NOE Ses 9 
Security €ConsideratilonS dirala se Mise Ne ween eee kole wre Nero 14 
Normative REfErenGes: said o u a Ne ene See Sates beets Behe 15 
Acknowledgements tidan daue agda 6 a ad iv dolls Mead Ka ge 15 
Introduction 
Purpose of This Document 


This document serves several purposes: 


1. rationalize and generalize ABNF for some existing IMAP 
extensions; 

2. collect the ABNF in one place in order to minimize cross 
references between documents; 

3. define building blocks for future extensions so that they can 


be used together in a compatible way. 


It is expected that a future revision of this document will be 
incorporated into a revision of RFC 3501. 


This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. 
It also includes part of the errata to RFC 3501. This document 
doesn’t specify any semantic changes to the listed RFCs. 


The ABNF in section 6 of RFC 2342 got rewritten to conform to the 


ABNF syntax as defined in RFC 4234 and to reference new non-terminals 


from RFC 3501. It was also restructured to allow for better 
readability. There were no changes "on the wire". 


Section 2 extends ABNF for SELECT, EXAMINE, CREATE, RENAME, FETCH/UID 
FETCH, STORE/UID STORE, SEARCH, and APPEND commands in a consistent 


manner. Extensions to all the commands but APPEND have the same 
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structure. Extensibility for the APPEND command was done slightly 
differently in order to preserve backward compatibility with existing 
extensions. 


Section 2 also defines a new ESEARCH response, whose purpose is to 
define a better version of the SEARCH response defined in RFC 3501. 


Section 3 defines the collected ABNF that replaces pieces of ABNF in 
the aforementioned RFCs. The collected ABNF got generalized to allow 
for easier future extensibility. 


1.2. Conventions Used in This Document 


In examples, "C:" and "S:" indicate lines sent by the client and 
server, respectively. 


The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 
in this document are to be interpreted as defined in "Key words for 
use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 


2. IMAP ABNF Extensions 
This section is not normative. It provides some background on the 


intended use of different extensions and it gives some guidance about 
how future extensions should extend the described commands. 


2.1. Optional Parameters with the SELECT/EXAMINE Commands 


This document adds the ability to include one or more parameters with 
the IMAP SELECT (section 6.3.1 of [IMAP4]) or EXAMINE (section 6.3.2 
of [IMAP4]) commands, to turn on or off certain standard behaviors, 
or to add new optional behaviors required for a particular extension. 


There are two possible modes of operation: 
o A global state change where a single use of the optional parameter 


will affect the session state from that time on, irrespective of 
subsequent SELECT/EXAMINE commands. 


o A per-mailbox state change that will affect the session only for 
the duration of the new selected state. A subsequent 
SELECT/EXAMINE without the optional parameter will cancel its 
effect for the newly selected mailbox. 


Optional parameters to the SELECT or EXAMINE commands are added as a 
parenthesized list of attribute/value pairs, and appear after the 
mailbox name in the standard SELECT or EXAMINE command. The order of 
individual parameters is arbitrary. A parameter value is optional 
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and may consist of atoms, strings, or lists in a specific order. If 
the parameter value is present, it always appears in parentheses (*). 
Any parameter not defined by extensions that the server supports must 
be rejected with a BAD response. 


Example: 


C: a SELECT INBOX (ANNOTATE) 
SE aen 
S: a OK SELECT complete 


In the above example, a single parameter is used with the SELECT 
command. 


Example: 


C: a EXAMINE INBOX (ANNOTATE RESPONSES ("UID Responses") 
CONDSTORE) 

See ee 

S: a OK EXAMINE complete 


In the above example, three parameters are used with the EXAMINE 
command. The second parameter consists of two items: an atom 
"RESPONSES" followed by a quoted string. 


Example: 


C: a SELECT INBOX (BLURDYBLOOP) 
S: a BAD Unknown parameter in SELECT command 


In the above example, a parameter not supported by the server is 
used. This results in the BAD response from the server. 


(") - if a parameter has a mandatory value, which can always be 
represented as a number or a seguence-set, the parameter value does 
not need the enclosing (). See ABNF for more details. 


2.2. Extended CREATE Command 


Arguments: mailbox name 
OPTIONAL list of CREATE parameters 


Responses: no specific responses for this command 
Result: OK - create completed 
NO - create failure: cannot create mailbox with 


that name 
BAD - argument (s) invalid 
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This document adds the ability to include one or more parameters with 
the IMAP CREATE command (see section 6.3.3 of [IMAP4]), to turn on or 
off certain standard behaviors, or to add new optional behaviors 
required for a particular extension. No CREATE parameters are 
defined in this document. 


Optional parameters to the CREATE command are added as a 
parenthesized list of attribute/value pairs after the mailbox name. 
The order of individual parameters is arbitrary. A parameter value 
is optional and may consist of atoms, strings, or lists in a specific 
order. If the parameter value is present, it always appears in 
parentheses (*). Any parameter not defined by extensions that the 
server supports must be rejected with a BAD response. 


(*) - if a parameter has a mandatory value, which can always be 
represented as a number or a sequence-set, the parameter value does 
not need the enclosing (). See ABNF for more details. 


2.3. Extended RENAME Command 


Arguments: existing mailbox name 
new mailbox name 
OPTIONAL list of RENAME parameters 


Responses: no specific responses for this command 
Result: OK - rename completed 
NO - rename failure: cannot rename mailbox with 


that name, cannot rename to mailbox with 
that name, etc. 
BAD - argument (s) invalid 


This document adds the ability to include one or more parameters with 
the IMAP RENAME command (see section 6.3.5 of [IMAP4]), to turn on or 
off certain standard behaviors, or to add new optional behaviors 
reguired for a particular extension. No RENAME parameters are 
defined in this document. 


Optional parameters to the RENAME command are added as a 
parenthesized list of attribute/value pairs after the new mailbox 
name. The order of individual parameters is arbitrary. A parameter 
value is optional and may consist of atoms, strings, or lists in a 
specific order. If the parameter value is present, it always appears 
in parentheses (*). Any parameter not defined by extensions that the 
server supports must be rejected with a BAD response. 
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(*) - if a parameter has a mandatory value, which can always be 
represented as a number or a sequence-set, the parameter value does 
not need the enclosing (). See ABNF for more details. 


2.4. Extensions to FETCH and UID FETCH Commands 


Arguments: sequence set 
message data item names or macro 
OPTIONAL fetch modifiers 


Responses: untagged responses: FETCH 

Result: OK - fetch completed 
NO — fetch error: cannot fetch that data 
BAD - command unknown or arguments invalid 


This document extends the syntax of the FETCH and UID FETCH commands 
(see section 6.4.5 of [IMAP4]) to include optional FETCH modifiers. 
No fetch modifiers are defined in this document. 


The order of individual modifiers is arbitrary. Each modifier is an 
attribute/value pair. A modifier value is optional and may consist 
of atoms and/or strings and/or lists in a specific order. If the 
modifier value is present, it always appears in parentheses (*). Any 
modifiers not defined by extensions that the server supports must be 
rejected with a BAD response. 


(") - if a modifier has a mandatory value, which can always be 
represented as a number or a seguence-set, the modifier value does 
not need the enclosing (). See ABNF for more details. 


2.5. Extensions to STORE and UID STORE Commands 


Arguments: message set 
OPTIONAL store modifiers 
message data item name 
value for message data item 


Responses: untagged responses: FETCH 

Result: OK - store completed 
NO — store error: cannot store that data 
BAD - command unknown or arguments invalid 


This document extends the syntax of the STORE and UID STORE commands 
(see section 6.4.6 of [IMAP4]) to include optional STORE modifiers. 
No store modifiers are defined in this document. 
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The order of individual modifiers is arbitrary. Each modifier is an 
attribute/value pair. A modifier value is optional and may consist 
of atoms and/or strings and/or lists in a specific order. If the 
modifier value is present, it always appears in parentheses (*). Any 
modifiers not defined by extensions that the server supports must be 
rejected with a BAD response. 


(*) - if a modifier has a mandatory value, which can always be 
represented as a number or a sequence-set, the modifier value does 
not need the enclosing (). See ABNF for more details. 


2.6. Extensions to SEARCH Command 
2.6.1. Extended SEARCH Command 
Arguments: OPTIONAL result specifier 
OPTIONAL [CHARSET] specification 


searching criteria (one or more) 


Responses: REQUIRED untagged response: SEARCH (*) 


Result: OK - search completed 
NO — search error: cannot search that [CHARSET] or 
criteria 
BAD - command unknown or arguments invalid 


This section updates definition of the SEARCH command described in 
section 6.4.4 of [IMAP4]. 


The SEARCH command is extended to allow for result options. This 
document does not define any result options. 


The order of individual options is arbitrary. Individual options may 
contain parameters enclosed in parentheses (**). If an option has 
parameters, they consist of atoms and/or strings and/or lists ina 
specific order. Any options not defined by extensions that the 
server supports must be rejected with a BAD response. 


(") - An extension to the SEARCH command may require another untagged 
response, or no untagged response to be returned. Section 2.6.2 
defines a new ESEARCH untagged response that replaces the SEARCH 
untagged response. Note that for a given extended SEARCH command the 
SEARCH and ESEARCH responses SHOULD be mutually exclusive, i.e., only 
one of them should be returned. 


(**) —- if an option has a mandatory parameter, which can always be 
represented as a number or a seguence-set, the option parameter does 
not need the enclosing (). See ABNF for more details. 
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2. ESEARCH untagged response 
Contents: one or more search-return-data pairs 


The ESEARCH response SHOULD be sent as a result of an extended SEARCH 
or UID SEARCH command specified in section 2.6.1. 


The ESEARCH response starts with an optional search correlator. If 
it is missing, then the response was not caused by a particular IMAP 
command, whereas if it is present, it contains the tag of the command 
that caused the response to be returned. 


The search correlator is followed by an optional UID indicator. If 
this indicator is present, all data in the ESEARCH response refers to 
UIDs, otherwise all returned data refers to message numbers. 


The rest of the ESEARCH response contains one or more search data 
pairs. Each pair starts with unique return item name, followed by a 
space and the corresponding data. Search data pairs may be returned 
in any order. Unless specified otherwise by an extension, any return 
item name SHOULD appear only once in an ESEARCH response. 


Example: S: * ESEARCH UID COUNT 5 ALL 4:19,21,28 
Example: S: * ESEARCH (TAG "a567") UID COUNT 5 ALL 4:19,21,28 
Example: S: * ESEARCH COUNT 5 ALL 1:17,21 

Extensions to APPEND Command 


The IMAP BINARY extension [BINARY] extends the APPEND command to 
allow a client to append data containing NULs by using the <literal8> 
syntax. The ABNF was rewritten to allow for easier extensibility by 
IMAP extensions. This document hasn’t specified any semantical 
changes to the [BINARY] extension. 


In addition, the non-terminal "literal8" defined in [BINARY] got 
extended to allow for non-synchronizing literals if both [BINARY] and 
[LITERAL+] extensions are supported by the server. 


The IMAP MULTIAPPEND extension [MULTIAPPEND] extends the APPEND 
command to allow a client to append multiple messages atomically. 
This document defines a common syntax for the APPEND command that 
takes into consideration syntactic extensions defined by both 
[BINARY] and [MULTIAPPEND] extensions. 
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3. Formal Syntax 


The following syntax specification uses the Augmented Backus-Naur 
Form (ABNF) notation as specified in [ABNF]. 


Non-terminals referenced but not defined below are as defined by 
[IMAP4]. 


Except as noted otherwise, all alphabetic characters are case- 
insensitive. The use of uppercase or lowercase characters to define 
token strings is for editorial clarity only. Implementations MUST 
accept these strings in a case-insensitive fashion. 


append = "APPEND" SP mailbox l"append-message 
7; only a single append-message may appear 
7; if MULTIAPPEND [MULTIAPPEND] capability 
7; is not present 

append-message = append-opts SP append-data 

append-ext = append-ext-name SP append-ext-value 


;; This non-terminal define extensions to 
7; to message metadata. 


append-ext-name tagged-ext-label 


append-ext-value= tagged-ext-val 


1; This non-terminal shows recommended syntax 
;; for future extensions. 


append-data = literal / literal8 / append-data-ext 


append-data-ext tagged-ext 

1; This non-terminal shows recommended syntax 
;; for future extensions, 

7; i.e., a mandatory label followed 


7; by parameters. 


append-opts = [SP flag-list] [SP date-time] *(SP append-ext) 
77 message metadata 


charset = atom / quoted 
7; Exact syntax is defined in [CHARSET]. 


create = "CREATE" SP mailbox 


[create-params ] 
7; Use of INBOX gives a NO error. 
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create-param-name 


create-param 


SP "(" create-param *( SP create-param) ")" 
= tagged-ext-label 


— create-param-name [SP create-param-value] 


create-param-value= tagged-ext-val 


esearch-response 


examine 


fetch 


fetch-modifiers 


fetch-modifier 


fetch-modif-params 


;; This non-terminal shows recommended syntax 
;; for future extensions. 


= "ESEARCH" [search-correlator] [SP "UID"] 
* (SP search-return-data) 
7; Note that SEARCH and ESEARCH responses 
;; SHOULD be mutually exclusive, 
7; i.e., only one of the response types 
;; should be 
7; returned as a result of a command. 


"EXAMINE" SP mailbox [select-params] 
7; modifies the original IMAP EXAMINE command 
7; to accept optional parameters 


"FETCH" SP sequence-set SP ("ALL" / "FULL" / 
"FAST" / fetch-att / 

"(" fetch-att "(SP fetch-att) ")") 
[fetch-modifiers] 

7; modifies the original IMAP4 FETCH command to 
;; accept optional modifiers 


SP "(" fetch-modifier "(SP fetch-modifier) ")" 
fetch-modifier-name [ SP fetch-modif-params ] 
= tagged-ext-val 


;; This non-terminal shows recommended syntax 
;; for future extensions. 


fetch-modifier-name = tagged-ext-label 


literal8 


Melnikov & Daboo 


w~ { " number ["+"] " } " CRLF *OCTET 

7; A string that might contain NULs. 

7; <number> represents the number of OCTETs 

7; in the response string. 

7; The "+" is only allowed when both LITERAL+ and 
1; BINARY extensions are supported by the server. 


Standards Track [Page 10] 


RFC 4466 Collected Extensions to IMAP4 ABNF 


mailbox-data 


Namespace 
Namespace-Command 


Namespace-Descr 


=/ Namespace-Response / 


esearch-response 


nil / "(" l"Namespace-Descr ")" 


"NAMESPACE" 


"(" string SP 


(DQUOTE QUOTED-CHAR DQUOTE / nil) 
* (Namespace-Response-Extension) ")" 


Namespace-Response-Extension = SP string SP 
"(" string *(SP string) 


Namespace-Response = 


1; if the IMAP server supports 


"y " 


"NAMESPACE" SP Namespace 
SP Namespace SP Namespace 
;; This response is currently only allowed 


[NAMESPACE]. 


1; The first Namespace is the Personal Namespace (s) 


;; The second Namespace is the Other Users’ 


1; The third Namespace is the Shared Namespace (s) 


rename = 


rename-params 


rename-param 


rename-param-name 


"RENAME" 


[rename-params] 
Use of INBOX as a destination gives 
a NO error, unless rename-params 


r 
£ 


1 


F 
# 


f 


is not empty. 


SP "(" rename-param *( 


SP mailbox SP mailbox 


SP rename-param) 


April 2006 


Namespace (s) 


my " 


rename-param-name [SP rename-param-value] 


tagged-ext-label 


rename-param-value= tagged-ext-val 
This non-terminal shows recommended syntax 
for future extensions. 


response-data = 


1 


z 


"am 


F 


# 


SP response-payload CRLF 


response-payload= resp-cond-state / resp-cond-bye / 


search = 


search-correlator 


Melnikov & Daboo 


"SEARCH" 


SP search-program 


[search-return-opts ] 


SP "(" "TAG" SP tag-string ")" 


Standards Track 


mailbox-data / message-data / capability-data 
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search-program — ["CHARSET" SP charset SP] 
search-key * (SP search-key) 
7; CHARSET argument to SEARCH MUST be 
7; registered with IANA. 


search-modifier-name SP search-return-value 
7; Note that not every SEARCH return option 
7; is required to have the corresponding 

;; ESEARCH return data. 


search-return-data 


Il 
n 
HU 


search-return-opts "RETURN" SP "(" [search-return-opt 


x (SP search-return-opt)] ")" 
search-return-opt = search-modifier-name [SP search-mod-params] 


search-return-value = tagged-ext-val 
7; Data for the returned search option. 
7; A single "nz-number"/"number" value 
;; can be returned as an atom (i.e., without 
7; Quoting). A seguence-set can be returned 
;; aS an atom as well. 


search-modifier-name = tagged-ext-label 


search-mod-params = tagged-ext-val 
;; This non-terminal shows recommended syntax 
;; for future extensions. 


select = "SELECT" SP mailbox [select-params] 
7; modifies the original IMAP SELECT command to 
7; accept optional parameters 


select -params SP "(" select-param "(SP select-param) ")" 


select -param = select-param-name [SP select-param-value] 
;; a parameter to SELECT may contain one or 
;; more atoms and/or strings and/or lists. 


select -param-name- tagged-ext-label 
select -param-value- tagged-ext-val 


;; This non-terminal shows recommended syntax 
;; for future extensions. 


status-att-list = status-att-val *(SP status-att-val) 
;; Redefines status-att-list from RFC 3501. 
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;; Status-att-val is defined in RFC 3501 errata 
status-att-val = ("MESSAGES" SP number) / 

("RECENT" SP number) / 

("UIDNEXT" SP nz-number) / 
("UIDVALIDITY" SP nz-number) / 
("UNSEEN" SP number) 

1; Extensions to the STATUS responses 
7; should extend this production. 

;; Extensions should use the generic 
7; syntax defined by tagged-ext. 


store = "STORE" SP seguence-set [store-modifiers] 
SP store-att-flags 
7; extend [IMAP4] STORE command syntax 
7; to allow for optional store-modifiers 


store-modifiers = SP "(" store-modifier *(SP store-modifier) 
") " 

store-modifier = store-modifier-name [SP store-modif-params] 

store-modif-params = tagged-ext-val 


This non-terminal shows recommended syntax 
;; for future extensions. 


store-modifier-name = tagged-ext-label 


string 
7; tag of the command that caused 
7; the ESEARCH response, sent as 


tag-string 


7; a string. 
tagged-ext = tagged-ext-label SP tagged-ext-val 
77 recommended overarching syntax for 
;; extensions 
tagged-ext-label = tagged-label-fchar "tagged-label-char 
;; Is a valid RFC 3501 "atom". 
tagged-label-fchar = ALPHA / "-" / s v / m.m 
tagged-label-char = tagged-label-fchar / DIGIT / ":" 
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tagged-ext-comp = astring / 

tagged-ext-comp "(SP tagged-ext-comp) / 

"(" tagged-ext-comp ")" 
1; Extensions that follow this general 
7; syntax should use nstring instead of 
7; astring when appropriate in the context 
1; of the extension. 
7; Note that a message set or a "number" 
7; can always be represented as an "atom". 
7; An URL should be represented as 
77 a "guoted" string. 


tagged-ext-simple — seguence-set / number 


tagged-ext-val = tagged-ext-simple / 
"(" [tagged-ext-comp] ")" 


4. Security Considerations 


This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. 
The updated documents must be consulted for security considerations 
for the extensions that they define. 


As a protocol gets more complex, parser bugs become more common 
including buffer overflow, denial of service, and other common 
security coding errors. To the extent that this document makes the 
parser more complex, it makes this situation worse. To the extent 
that this document makes the parser more consistent and thus simpler, 
the situation is improved. The impact will depend on how many 
deployed IMAP extensions are consistent with this document. 
Implementers are encouraged to take care of these issues when 


extending existing implementations. Future IMAP extensions should 
strive for consistency and simplicity to the greatest extent 
possible. 


Extensions to IMAP commands that are permitted in NOT AUTHENTICATED 
state are more sensitive to these security issues due to the larger 
possible attacker community prior to authentication, and the fact 
that some IMAP servers run with elevated privileges in that state. 
This document does not extend any commands permitted in NOT 
AUTHENTICATED state. Future IMAP extensions to commands permitted in 
NOT AUTHENTICATED state should favor simplicity over consistency or 
extensibility. 
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